Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / tools4c.arc / REFMAN.TXT < prev next >

Wrap

Text File | 1988-12-27 | 51.0 KB | 1,300 lines

TOOLS FOR C Application Development Package FUNCTION REFERENCE MANUAL Shareware Distribution Version 1.0 This version of TOOLS FOR C and it's associated manuals and support files may be freely copied and distributed as long as it is distributed in it's entirety and no fees other than nominal handling fees are charged. The routines in this library are NOT Public Domain. This is copyrighted material. The intent behind distributing this version of TOOLS FOR C is to allow you to use the package on a trial basis and determine if it meets your needs. If you find yourself using this package, you MUST register by sending $45.00 to the address listed below. Upon receipt of your registration fee we will send you an expanded manual, compiled libraries for all of the memory models available with your compiler, and the complete source code to the library. In NO EVENT may you use any of the routines in TOOLS FOR C for commercial purposes until you register your copy. We feel that you will find the value of TOOLS FOR C far exceeds the registration fee and we at BP SOFTWARE SOLUTIONS, INC. thank you in advance for your support. BP Software Solutions, Inc. 642 N. Commodore Drive Plantation, Fl. 33325 Copyright (C) 1987 BP Software Solutions Inc. All Rights Reserved page 2 Table of Contents Screen and Cursor Control . . . . . . . . 4 cls() . . . . . . . . . . . . . . . . 4 cursor() . . . . . . . . . . . . . . 4 curs() . . . . . . . . . . . . . . . 4 get_curs() . . . . . . . . . . . . . 4 get_cursor() . . . . . . . . . . . . 4 cursor_type() . . . . . . . . . . . . 5 normal_cursor() . . . . . . . . . . . 5 block_cursor() . . . . . . . . . . . 5 scroll() . . . . . . . . . . . . . . 5 Keyboard Functions . . . . . . . . . . . . 6 key() . . . . . . . . . . . . . . . . 6 shift_stat() . . . . . . . . . . . . 6 char_waiting() . . . . . . . . . . . 6 Character Output . . . . . . . . . . . . . 7 write_a() . . . . . . . . . . . . . . 7 write_am() . . . . . . . . . . . . . 7 write_ac() . . . . . . . . . . . . . 7 write_al() . . . . . . . . . . . . . 7 write_tty() . . . . . . . . . . . . . 8 write_str() . . . . . . . . . . . . . 8 print_string() . . . . . . . . . . . 8 aprintf() . . . . . . . . . . . . . . 8 String Functions . . . . . . . . . . . . . 9 delete_leading() . . . . . . . . . . 9 del_lead_wht() . . . . . . . . . . . 9 delete_trailing() . . . . . . . . . . 9 del_trl_wht() . . . . . . . . . . . . 9 right_just_str() . . . . . . . . . . 9 left_just_str() . . . . . . . . . . . 10 center_str() . . . . . . . . . . . . 10 insert_str() . . . . . . . . . . . . 10 Video Routines . . . . . . . . . . . . . . 11 vid_type() . . . . . . . . . . . . . 11 save_scn() . . . . . . . . . . . . . 11 rest_scn() . . . . . . . . . . . . . 12 video_on() . . . . . . . . . . . . . 12 video_off() . . . . . . . . . . . . . 12 change_att() . . . . . . . . . . . . 12 h_line() . . . . . . . . . . . . . . 13 v_line() . . . . . . . . . . . . . . 13 vert_line() . . . . . . . . . . . . . 13 shuffle_image() . . . . . . . . . . . 14 draw_box() . . . . . . . . . . . . . 14 draw_ex_box() . . . . . . . . . . . . 14 fill_area() . . . . . . . . . . . . . 15 fill_box() . . . . . . . . . . . . . 15 set_vid_mode() . . . . . . . . . . . 15 get_vid_mode() . . . . . . . . . . . 15 page 3 Window Related Functions . . . . . . . . . 16 open_window() . . . . . . . . . . . . 16 open_ex_window() . . . . . . . . . . 16 close_window() . . . . . . . . . . . 16 clear_window() . . . . . . . . . . . 16 activate() . . . . . . . . . . . . . 17 create_window() . . . . . . . . . . . 17 title_window() . . . . . . . . . . . 18 clear_wndw_title() . . . . . . . . . 18 scroll_window() . . . . . . . . . . . 18 cursor_window() . . . . . . . . . . . 19 move_window() . . . . . . . . . . . . 19 wprint_string() . . . . . . . . . . . 19 wprint_string_att() . . . . . . . . . 19 wprintf() . . . . . . . . . . . . . . 20 fprint_window() . . . . . . . . . . . 20 fill_window() . . . . . . . . . . . . 20 Menu Routines . . . . . . . . . . . . . . 21 menu() . . . . . . . . . . . . . . . 21 Data Entry Functions . . . . . . . . . . . 23 get_field() . . . . . . . . . . . . . 23 edit_field() . . . . . . . . . . . . 23 update_ins_flag() . . . . . . . . . . 24 Index . . . . . . . . . . . . . . . . . . 25 page 4 Screen and Cursor Control FUNCTION NAME: cls() SYNOPSIS: void cls(); DESCRIPTION: This function clears the screen and homes the cursor. FUNCTION NAME: cursor() curs() SYNOPSIS: void cursor(col, row) int col; int row; void curs(pos) int pos; DESCRIPTION: These functions place the cursor at the specified column and row or position. cursor() places the cursor at the specified col and row. curs() places the cursor at the position specified by the int "pos" where the high eight bits of "pos" are the row number and the low eight bits are the column number. This is the same encoding returned by get_curs(). In the case of cursor() the upper left-hand corner of the screen is 0,0, for curs() it is 0. FUNCTION NAME: get_curs() get_cursor() SYNOPSIS: curs_pos = get_curs( void ) int curs_pos; /* current col, row of cursor */ void get_cursor( col, row ); int *col; /* pointer to column variable */ int *row; /* pointer to row variable */ DESCRIPTION: These functions return the current position of the cursor. get_curs() returns an integer with the high 8-bits set to the row number and the low 8-bits set to the Column number. get_cursor() places the current column and row position into the integer variables pointed to by col and row. page 5 FUNCTION NAME: cursor_type() SYNOPSIS: void cursor_type( curs_num ) int curs_num; /* type code of desired cursor */ DESCRIPTION: cursor_type() changes the hardware cursor size and shape to one of nine predefined cursors as selected by the parameter curs_num. The cursor is smallest when cur_num == 1 and grows steadily larger until it reaches the size of a full character block at curs_num == 8. In the special case of curs_num == 0, the cursor is blanked. FUNCTION NAME: normal_cursor() block_cursor() SYNOPSIS: void normal_cursor( void ) void block_cursor( void ) DESCRIPTION: These cursor shape control functions set the cursor to either a normal two bottom scan line cursor or a block occupying the full character position. FUNCTION NAME: scroll() SYNOPSIS: void scroll(u_col,u_row,l_col,l_row,lines,dir,attr); int u_col; /* upper col */ int u_row; /* upper row */ int l_col; /* lower col */ int l_row; /* lower row */ int lines; /* number of lines to scroll */ int dir; /* direction to scroll */ int attr; /* attribute */ DESCRIPTION: This function scrolls a region of the screen using the specified video attribute. Lines refers to the number of lines to scroll. If "lines" equals zero, then the screen will clear using 'blank' characters (spaces) with the specified video attribute. The direction is specified with either 0=up or 1=down. page 6 Keyboard Functions FUNCTION NAME: key() SYNOPSIS: ret_code = key( void ); int ret_code; /* integer return key code */ DESCRIPTION: Returns the next character in the keystroke buffer. If the buffer is empty, the routine waits for the next keystroke. If the key is one of the normal ascii characters, it returns that integer value. If it is one of the extended keycodes ( function keys, cursor keys, etc. ), the high eight bits of the return integer contains the scan code for that key and the low eight bits contain zero. KEY.H defines integer values to uniquely define most of the keys on an IBM compatible keyboard. RETURNS: An integer key_code. FUNCTION NAME: shift_stat() SYNOPSIS: ret_code = shift_stat( void ) int ret_code; /* integer status code */ DESCRIPTION: keybd_stat() returns and integer value with the current shift status of the keyboard as reported by the BIOS Get Shift Status function (INT 16 H, service 2). The status of various keys can be determined by decoding the individual bits of the returned integer value as follows. bit 0 == 1; Right Shift key depressed bit 1 == 1; Left Shift key depressed bit 2 == 1; Control key depressed bit 3 == 1; Alt key depressed bit 4 == 1; Scroll Lock is active bit 5 == 1; Num Lock is active bit 6 == 1; Caps Lock is active bit 7 == 1; Insert State is active FUNCTION NAME: char_waiting() SYNOPSIS: ret_code = char_waiting( void ) int ret_code; /* TRUE or FALSE */ DESCRIPTION: Returns TRUE (1) if a character is waiting in the keyboard buffer or FALSE (0) if not. page 7 Character Output FUNCTION NAME: write_a() SYNOPSIS: void write_a(ch,att) char ch; int att; DESCRIPTION: This function writes a character using a specified video attribute at the current cursor location. The cursor is not moved. FUNCTION NAME: write_am() SYNOPSIS: void write_am(ch,att,count); char ch; int att; int count; DESCRIPTION: This function writes multiple characters to the screen with a specified video attribute. This function is designed to write characters to the current row only. If the count is greater than the remaining spaces on that row, the results may be unpredictable. If the count is 'zero' (0) no characters will be written. FUNCTION NAME: write_ac() SYNOPSIS: void write_ac( ch, att ) char ch; int att; DESCRIPTION: This function writes a character with specified attribute and advances the cursor one position, wrapping to a new line if needed. The screen will not scroll, however, and the cursor will not advance past the last position of line 25. FUNCTION NAME: write_al() SYNOPSIS: void write_al(col, row, attr, ch); int col; int row; int attr; char ch; DESCRIPTION: This function writes a character with the specified attribute at the specified location. The location of the cursor makes no difference as it is not checked or used by this routine. page 8 FUNCTION NAME: write_tty() SYNOPSIS: void write_tty( ch ); char ch; DESCRIPTION: This function writes a specified character to the screen using the bios function "write character as TTY". No attribute is written with the character, however, the cursor is advanced. This function recognizes the 'Bell', 'Backspace', 'Return' & 'Line-Feed' ascii characters. FUNCTION NAME: write_str() SYNOPSIS: void write_str(col,row,string,att) int col,row; char *string; int att; DESCRIPTION: Writes a string to specified location on the screen using the specified attribute. The position of the cursor is of no importance as it is not used or moved by this function. Lines will wrap to the next line if one is available. The screen will not scroll at the end of the last line. If you attempt to write past the end of the last line, those characters are lost. FUNCTION NAME: print_string() SYNOPSIS: void print_string( string,att ) char *string; int att; DESCRIPTION: This function prints a string with a given attribute beginning at the current cursor position. The '\n', '\t', and '\r' characters are supported. The string wraps at the end of the line and scrolls at the end of the screen. The cursor is left positioned one character to the right of the last character in the string. FUNCTION NAME: aprintf() SYNOPSIS: void aprintf(att, string, arg(s)...); DESCRIPTION: This routine prints a string and expands all arguments, exactly like printf, and writes the string to the screen starting at the current cursor position using the supplied attribute "att". page 9 String Functions FUNCTION NAME: delete_leading() del_lead_wht() SYNOPSIS: void delete_leading(str) char *str; void del_lead_wht(str) char *str; DESCRIPTION: These routines remove any leading white space or control characters from a string. In the case of del_lead_wht() any space or tab characters are deleted from the front of a string until the first non space/tab is reached. del_leading() does the same for any character with an ascii value below 21h. FUNCTION NAME: delete_trailing() del_trl_wht() SYNOPSIS: void delete_trailing(str) char *str; void del_trl_wht(str) char *str; DESCRIPTION: These functions remove any white space or control codes from the end of a string. del_trl_wht() removes any space or tab characters from the end of a string until a non space/tab is reached. delete_trailing() does the same for any character below ascii 21h. FUNCTION NAME: right_just_str() SYNOPSIS: void right_just_str(text,outbuffer,width) char *text; char *outbuffer; int width; DESCRIPTION: Pads the output string with spaces and copies the text string to the output buffer so that the end of the text winds up at end of the output string. If the text string is longer than the specified width, the text is truncated to fit. The output buffer must be at least one character longer than "width" to allow for the null byte at the end of the string. page 10 FUNCTION NAME: left_just_str() SYNOPSIS: void left_just_str(text,outbuffer,width) char *text; char *outbuffer; int width; DESCRIPTION: Pads spaces to the end of a string to the specified width. If the string already is as long as or longer than the specified width, the string is truncated to that width. The output buffer must be at least one character longer than "width" to allow for the null byte at the end of the string. FUNCTION NAME: center_str() SYNOPSIS: void center_str(text,outbuffer,width) char *text; char *outbuffer; int width; DESCRIPTION: Produces a string in "outbuffer" with the specified text string centered between enough spaces to make the output string length equal to "width"(excluding the null byte). If the text string length is longer than the specified width, then the text is truncated to fill the buffer. The output buffer is assumed to be long enough to hold the centered string. If the string is to be centered between an odd number of characters, the extra character is placed at the end of the string. FUNCTION NAME: insert_str() SYNOPSIS: int insert_str( text1, text2, out_buffer, n) char *text1; char *text2; char *out_buffer; int n; DESCRIPTION: Inserts text2 into text1 immediately following the n'th character of text1, depositing the combined string in "out_buffer". It is the caller's responsibility to ensure that the output buffer is large enough. This function returns the combined length of the result string. If text1 is shorter than n, text2 is concatenated to text1. page 11 Video Routines FUNCTION NAME: vid_type() SYNOPSIS: ret_code = vid_type( void ) int ret_code; DESCRIPTION: This is the routine used to determine the current video configuration of the machine. It checks the current video mode to determine if it is 2, 3, or 7. If the current mode is 7 (Monochrome), then the global variables reflecting the present screen configuration are left set for a monochrome card. If the mode is 2 (BW80) or 3 (CO80), the variables are set to reflect a CGA card. The "_color" variable is only set if the current mode is 3. The function normally returns OK (zero). If any mode other than 2, 3, or 7 is set, the function returns ERROR (-1). FUNCTION NAME: save_scn() SYNOPSIS: void save_scn(ucol, urow, lcol, lrow, buff_address) int ucol; int urow; int lcol; int lrow; char *buff_address; DESCRIPTION: This routine saves the portion of the screen defined by the boundary variables to the buffer pointed to by buff_address. No checking is or can be done to ensure that the buffer is big enough. vid_type() must be called at least once before calling this function to properly set the global variables which tell it where the screen buffer is and whether or not to wait for retrace. page 12 FUNCTION NAME: rest_scn() SYNOPSIS: void rest_scn(ucol, urow, lcol, lrow, buff_address) int ucol; int urow; int lcol; int lrow; char *buff_address; DESCRIPTION: This routine is the opposite of save_scn(). It takes a previously saved screen image and returns it to the specified location. As in save_scn, vid_type must be called at least once before calling this routine. FUNCTION NAME: video_on() video_off() SYNOPSIS: void video_on( void ); void video_off( void ); DESCRIPTION: These two functions turn the video on and off on a Color Graphics card to allow writing to the screen without snow. If the mode is set for a Monochrome card, they simply return and no action is taken. vid_type() must be called at least once before calling either of these routines to determine what mode is presently set. FUNCTION NAME: change_att() SYNOPSIS: old_att = change_att(col,row,len,att) int old_att; /* old attribute at start location */ int col; /* start column */ int row; /* start row */ int len; /* number of characters to change */ int att; /* new attribute */ DESCRIPTION: Changes the video attribute, starting at the specified col and row, for the number of characters "len". It returns the attribute byte found at the starting point. page 13 FUNCTION NAME: h_line() SYNOPSIS: void h_line(col, row, attr, char, int count); int col; /* start column */ int row; /* start row */ int attr; /* display attribute */ int char; /* line character */ int count; /* line length */ DESCRIPTION: Writes multiple copies of the character using the attribute specified. They will wrap to the next line if necessary. If the count is zero, no characters are written. FUNCTION NAME: v_line() SYNOPSIS: void v_line( col, row, attr, char, number); int col; /* start column */ int row; /* start row */ int attr; /* display attribute */ int char; /* line character */ int count; /* line length */ DESCRIPTION: Draws a vertical line starting at col, row, down "number" of characters using attribute "attr". FUNCTION NAME: vert_line() SYNOPSIS: void vert_line(char,attr,count); int char; /* char to use for vertical line */ int attr; /* display attribute of line */ int count; /* length of line */ DESCRIPTION: Draws a vertical line starting at the current cursor position, down the "count" number of characters, using the specified character and display attribute. page 14 FUNCTION NAME: shuffle_image() SYNOPSIS: void shuffle_image(pointer,temp) WNDW *pointer; char *temp; DESCRIPTION: Takes a pointer to a window and a pointer to a temporary storage area as arguments. The storage area must be as large as the window's image buffer. The routine stores the present screen image at the window location in the window's image buffer and puts the old contents of the image buffer back on the screen. This routine is called by activate() to bring an overlaid window to the top. FUNCTION NAME: draw_box() draw_ex_box() SYNOPSIS: void draw_box(lcol,urow,rcol,lrow,box,linea,filla) int lcol; /* left column */ int urow; /* upper row */ int rcol; /* right column */ int lrow; /* lower row */ WNDW *box; /* pointer to window structure*/ int linea; /* border video attribute */ int filla; /* fill video attribute */ void draw_ex_box(lcol,urow,rcol,lrow,box,linea,filla,speed) int lcol; /* left column */ int urow; /* upper row */ int rcol; /* right column */ int lrow; /* lower row */ WNDW *box; /* pointer to window structure*/ int linea; /* border video attribute */ int filla; /* fill video attribute */ int speed; /* exploding box drawing speed*/ DESCRIPTION: These functions draw a box on the screen. draw_box() simply draws the box on the screen while draw_ex_box() repetitively draws bigger and bigger boxes, starting at the apparent center of the box expanding outwards until the final box size is achieved. No screen saving is done here. Both routines take as arguments the upper left and lower right corner cursor locations, the address of a window structure where the correct characters for the border and fill can be found, the border attribute and fill character attribute. draw_ex_box() takes another argument, "speed", which controls the rate at which the box grows. 0 is the fastest speed, 16000 is the slowest. page 15 FUNCTION NAME: fill_area() SYNOPSIS: void fill_area(lcol,urow,rcol,lrow,ch,attr) int lcol; /* left column */ int urow; /* upper row */ int rcol; /* right column */ int lrow; /* left row */ int ch; /* character to fill */ int attr; /* video attribute */ DESCRIPTION: Quickly fills the rectangular area of the screen defined by the parameters with the specified character and video attribute. FUNCTION NAME: fill_box() SYNOPSIS: void fill_box(lcol,urow,rcol,lrow,ch,attr) int lcol; /* left column */ int urow; /* upper row */ int rcol; /* right column */ int lrow; /* left row */ int ch; /* character to fill */ int attr; /* video attribute */ DESCRIPTION: Much like fill_area() except that fill_box() fills the interior of the box specified by the bounding rows and columns with any character and attribute. Please note that the area filled is inside, not on, the specified rows and columns. FUNCTION NAME: set_vid_mode() get_vid_mode() SYNOPSIS: void set_vid_mode( modenum ) int modenum /* video mode number */ modenum = get_vid_mode( void) int modenum /* current video mode */ DESCRIPTION: These routines simply either return the int value of the current video mode or change it as specified. page 16 Window Related Functions FUNCTION NAME: open_window() open_ex_window() SYNOPSIS: int open_window(wind) WNDW *wind; int open_ex_window(wind,speed) WNDW *wind; int speed; DESCRIPTION: Takes a pointer to a window structure as an argument and calls create_window(). They then draw the box on the screen and fill it using the characters and attributes found in the structure. In the case of open_ex_window() the box is drawn in an exploding fashion, starting at the center of the box, growing outward to it's final size. The speed of the growth is determined by the variable "speed", with 16,000 being the slowest and 0 the fastest. FUNCTION NAME: close_window() SYNOPSIS: void close_window(wind) WNDW *wind; DESCRIPTION: Closes the window pointed to by "wind". If the window is not the active window, it is first activated. Finally memory allocated to it's screen buffer is then freed. Attempting to close a window that is not open will most likely crash the system. As a matter of fact, you can count on it! FUNCTION NAME: clear_window() SYNOPSIS: void clear_window( void ) DESCRIPTION: Clears the active window as cls() would do for the entire screen. The cursor position is not affected, however. page 17 FUNCTION NAME: activate() SYNOPSIS: void activate(wind) WNDW *wind; DESCRIPTION: Checks to see if "wind" is currently the active window. If it is not, it is made the active window, overlying any other windows which may have been overlaying it. Upon leaving activate_wind(), the doubly linked list of open_windows is updated so that "wind" is last and the global "last_wndw" points to it. FUNCTION NAME: create_window() SYNOPSIS: ret_code = create_window(new_window) WNDW *new_window; /* window pointer */ int ret_code; /* OK or ERROR */ DESCRIPTION: Is called by open_window() or open_ex_window(). It calculates the size of the image buffer and allocates memory for it. It then adds the new window to the end of the doubly linked list of open windows and saves the image at the window position. The structure variables for image size, image buffer pointer, previous and next windows are updated here. Nothing is drawn on the screen in this routine. RETURNS: ERROR (-1) if malloc is unable to allocate the storage for the image buffer, otherwise, OK (zero). page 18 FUNCTION NAME: title_window() SYNOPSIS: void title_window(window,string,attr,just_code) WNDW *window; /* pointer to window */ char *string; /* pointer to title text */ int attr; /* text display attribute*/ int just_code; /* justification code */ DESCRIPTION: Prints the string to the top of the specified window using the supplied attribute. The justification code is as follows... 1 == Top-Left; 2 == Top-Center; 3 == Top-Right; 4 == Bottom Left; 5 == Bottom Center; 6 == Bottom Right; e.g. If the code is ONE, the string is left justified. If it is TWO, the string is right justified, etc. Strings longer than the window length minus two characters are truncated. The window is activated if it is not already active. FUNCTION NAME: clear_wndw_title() SYNOPSIS: void clear_wndw_title(window,row) WNDW *window; /* window pointer */ int row; /* upper or lower row */ DESCRIPTION: Redraws the top or bottom of the specified window with the default border chars and attr for that window. The window is activated if it is not already active. "row" is decoded as follows: 0 == Top-Row; 1 == Bottom-Row; FUNCTION NAME: scroll_window() SYNOPSIS: void scroll_window(num,dir) int num; /* number of lines to scroll */ int dir; /* direction of scroll */ DESCRIPTION: scrolls the active window "num" lines in direction "dir" where: dir == 0, scroll up; dir == 1, scroll down; page 19 FUNCTION NAME: cursor_window() SYNOPSIS: void cursor_window(col,row) int col; int row; DESCRIPTION: Moves the cursor to the specified column and row relative to the window. 0,0 is the upper left hand corner of the window, just inside the border. If a row or col argument is specified which is larger than the number of rows or columns in the window, that row or column position is set to the maximum value which will keep the cursor just inside the window border. FUNCTION NAME: move_window() SYNOPSIS: void move_window(window,direction,count) WNDW *window; int direction; int count; DESCRIPTION: Moves the window "count" spaces in the direction indicated, where 1 = LEFT 2 = UP 3 = RIGHT 4 = DOWN If the "count" argument is greater than the number of spaces available on the screen, the window is only moved the number of spaces where all of the window will still be displayed. FUNCTION NAME: wprint_string() wprint_string_att() SYNOPSIS: void wprint_string( string ) char *string; void wprint_string_att( string,att ) char *string; int att; DESCRIPTION: wprint_string() writes a string to the currently active window using that window's fill attribute as it's attribute. Lines wrap at the window border, and scroll on the last line. The characters '\n', '\t', and '\r' are supported. wprint_string_att() is identical, except that the specified attribute is used instead of the window's fill attribute. These routines are significantly faster than wprintf() page 20 FUNCTION NAME: wprintf() SYNOPSIS: char_num = wprintf( control, arg(s); char *control; indeterminate arg(s); int char_num; DESCRIPTION: Formats a printf type string with a variable number of arguments and writes it to the currently active window. The formatted sting is stored in a 256 byte global buffer "temp_str". There is no checking to see if the returned string exceeds this value. RETURNS: An integer value set to the number of characters in the formatted string. FUNCTION NAME: fprint_window() SYNOPSIS: void fprint_window(window, text, arg1, ...) WNDW *window; /* window pointer */ char *text; /* text spring pointer */ indeterminate arg1; /* beginning of argument */ /* list, if any */ DESCRIPTION: Much like wprintf, except that instead of writing to the currently active window, any open window can be specified. That window is then activated if it is not already the active window. FUNCTION NAME: fill_window() SYNOPSIS: fill_window( wind_ptr ) WNDW *wind_ptr; DESCRIPTION: Quickly fills the interior of the window using the fill character and fill attribute defined in the window structure. page 21 Menu Routines FUNCTION NAME: menu() SYNOPSIS: ret_val = menu(menu_ptr) MENU *menu_ptr; /* pointer to menu struct*/ int ret_val; /* OK or ERROR */ DESCRIPTION: Only one parameter is required to execute a menu, a pointer to a struct MENU. This structure contains, or points to, all of the information necessary to open a menu window, make a selection, then run the appropriate program or routine. Error handling and context sensitive help are included. Struct MENU contains pointers to a window structure, a window title text string, and a screen writing function. It also contains integer values for default video attributes, a menu cursor type code, and a window title justification code. These items define the menu's video display. The function pointers to help and error functions, and the integer values for the exit and help hot keys define the menu's behavior. The last two items, a pointer to the first structure in an array of SEL structures and the number of SELs in the array, define the individual menu selections. Struct SEL contains a pointer to the selection text. The start column & row where this text will be displayed in the menu window (the position is referenced to the window, not the full screen). Integer values for select and unselect attributes if the default values defined in the MENU structure are not to be used (set to zero to use the defaults). Integer values for 2 activate keys. A pointer to a function to be called or a program to be executed (one of these must be set to a NULL depending on which is not used). A pointer to a help function (this must be a NULL pointer if none is provided). Finally an integer which, if zero, signifies that the menu should be reentered after completion of the selected routine or program. If non_zero, then the menu is exited and control passes back to the routine which called it. whether the return to the menu or the menu's caller should be executed at the end of the function. Three types of pseudo cursors are supported. If pcursor_type == 0 then the cursor is as long as the selected text string. If pcursor_type == 1 then the cursor is as long as the longest text string in the selection list. If pcursor_type == 2 then the cursor is as long as the window is wide. All sections functions must return an integer value.. this value should be zero for a normal return and any other value for an error condition. This integer is passed to the menu's user defined error function where it must be decoded by the programmer. If the error function is called with a parameter of zero a key stroke error is indicated. page 22 Calling the menu routine is easy. Setting up all of the necessary structures and arrays of structures, then stuffing them with the appropriate values is not. We understand how difficult and error prone hand coding the menu structures would be, so we have included in the package MENUGEN.EXE which automates the process. While using MENUGEN you interactively define the menu on screen. When complete, MENUGEN writes the control structures to a file which you then include in your source code. The operation of MENUGEN is covered more thoroughly in it's own section. RETURNS: An int value. OK (zero) or ERROR ( -1) Listings of typedef MENU and SEL typedef struct MENU { struct WNDW *menu_window; /* Pointer to the menu window structure */ int default_non_select_att;/* Usually the same as window fill attr */ int default_cursor_att; /* Attribute of items when selected */ int title_format; /* Position of menu title on border(1-6)*/ int window_title_att; /* Video attribute of menu title */ char *window_title_text; /* Pointer to menu title text string */ int pcursor_type; /* Type of selection cursor (0-2) */ int exit_key; /* Hot key to exit menu, Usually ESC */ int help_key; /* Hot key to call help function, if any*/ int (*menu_text)(); /* Ptr to function to write text to scrn*/ int (*error_fn)(); /* Ptr to user supplied error handler */ struct SEL *sel_list; /* Ptr to the first in array of SELs */ int num_sel; /* Number of menu selections */ } MENU; typedef struct SEL{ char *text; /* Pointer to item selection text string */ int start_col; /* Starting col in window for text string */ int start_row; /* Starting row in window for text string */ int sel_att; /* Item sel video attr, Zero for default */ int unsel_att; /* Item unselected video attribute or Zero*/ int activate_key_1; /* First Activate hot key */ int activate_key_2; /* Second Activate hot key */ int (*do_function)(); /* Ptr to selected function or NULL */ char *exe_call; /* Ptr to program name string or NULL */ int (*help_function)(); /* Ptr to optional help fctn or NULL */ int exit; /* exit menu after command, Zero if no */ } SEL; page 23 Data Entry Functions FUNCTION NAME: get_field() SYNOPSIS: ch = get_field(buffer,length,attr,just_code,under_line) char *buffer; /* pointer to data buffer */ int length; /* maximum length of data */ int attr; /* on screen attribute */ int just_code; /* left(0) or right(1) justify */ int under_line; /* underline(1) field or not(0)*/ int ch; /* last keycode as def in key.h*/ DESCRIPTION: Gets a string into a data buffer, allowing editing and writing to the screen using attributes. Left or right justification is supported. The buffer MUST be length + 1 byte long. Justification codes are 0 = left, 1 = right. The routine exits whenever a keystroke with a return code less than 32 (space) or greater than 256 (as defined in KEY.H) is entered or the cursor reaches the end of the field. RETURNS: It returns a code indicating the last keystroke or a zero if the end of the field was reached. FUNCTION: edit_field() SYNOPSIS: ch = edit_field(buff,length,attr,underline) char *buff; /* storage buffer */ int length; /* field length */ int attr; /* display attribute*/ int underline; /* underline code */ int ch; /* last keystroke */ DESCRIPTION: This function is similar to get_field() except that it first displays at the current cursor position the contents of "buff" which can then be edited. Only left justification is supported. RETURNS: It returns a code indicating the last keystroke or a zero if the end of the field was reached. page 24 FUNCTION NAME: update_ins_flag() SYNOPSIS: void update_ins_flag() DESCRIPTION: This function is called each time the insert key is pressed while in the get_field() data input function. This one is a null routine which can be replaced by one of your own. This is useful for doing things like updating an on screen prompt to reflect the current state of the global insert/overwrite flag "insert_flag". page 25 INDEX activate() . . . . . (17) left_just_str() . . (10) aprintf() . . . . . ( 8) menu() . . . . . . . (21) block_cursor() . . . ( 5) move_window() . . . (19) center_str() . . . . (10) normal_cursor() . . ( 5) change_att() . . . . (12) open_ex_window() . . (16) char_waiting() . . . ( 6) open_window() . . . (16) clear_window() . . . (14) print_string() . . . ( 8) clear_wndw_title() . (18) rest_scn() . . . . . (11) close_window() . . . (16) right_just_str() . . ( 9) cls() . . . . . . . ( 4) save_scn() . . . . . (11) create_window() . . (17) scroll() . . . . . . ( 5) curs() . . . . . . . ( 4) scroll_window() . . (18) cursor() . . . . . . ( 4) set_vid_mode() . . . (15) cursor_window() . . (19) shift_stat() . . . . ( 6) del_lead_wht() . . . ( 9) shuffle_image() . . (14) del_trl_wht() . . . ( 9) title_window() . . . (18) delete_leading() . . ( 9) update_ins_flag() . (24) delete_trailing() . ( 9) v_line() . . . . . . (13) draw_box() . . . . . (14) vert_line() . . . . (13) draw_ex_box() . . . (14) vid_type() . . . . . (11) edit_field() . . . . (23) video_off() . . . . (12) fill_area() . . . . (15) video_on() . . . . . (12) fill_box() . . . . . (15) wprint_string() . . (19) fill_window() . . . (20) wprint_string_att() (19) fprint_window() . . (20) wprintf() . . . . . (20) get_curs() . . . . . ( 4) write_a() . . . . . ( 7) get_cursor() . . . . ( 4) write_ac() . . . . . ( 7) get_field() . . . . (23) write_al() . . . . . ( 7) get_vid_mode() . . . (15) write_am() . . . . . ( 7) h_line() . . . . . . (12) write_str() . . . . ( 8) insert_str() . . . . (10) write_tty() . . . . ( 8) key() . . . . . . . ( 6)